About {gs}

gs is a grammar of recurring calendar events, implemented as an R package. It enables users to easily create and work with schedules, even in cases when the pattern of events is irregular.

gs does this by providing a set of simple to understand functions for making schedules along with functions for combining them to form more complex ones.

The gs grammar is both flexible and declarative. The flexibility allows users to compose arbitrarily complex schedules from simple and intuitive buildings blocks. Because the grammar is declarative, the user need not concern themselves with the details of how a particular schedule works, rather they can specify what they want from a schedule and let gs implement it for them.

About me

My name is James Laird-Smith and I am a data analyst at the Financial Times in London.

Home

Introducing {gs}:
A grammar of recurring calendar events

James Laird-Smith

The Financial Times (FT)

Simple examples

Every 35 days

on_every_nth(35, "days", starting = dmy("28/01/2020")) %>% 
  schedule_days(during = 2020)

 [1] "2020-01-28"
 [2] "2020-03-03"
 [3] "2020-04-07"
 [4] "2020-05-12"
 [5] "2020-06-16"
 [6] "2020-07-21"
 [7] "2020-08-25"
 [8] "2020-09-29"
 [9] "2020-11-03"
[10] "2020-12-08"

To schedule days in increments from a certain date, we use the on_every_nth() function.

In this case we specify:

The number of increments between events is 35
The type of increment is “days”
The start date is today.

Friday the 13th

on_fri_thirteenth <- 
  on_wday("Fri") %>% 
  only_occur(on_mday(13))

on_fri_thirteenth %>% 
  schedule_days(from = 2020, to = 2022)

[1] "2020-03-13"
[2] "2020-11-13"
[3] "2021-08-13"
[4] "2022-05-13"

Friday the 13th can be thought of as the intersection of:

The schedule of all Fridays, found using the on_wday() function.
The schedule of all 13th days of the month, using the on_mday() function.

The intersection of these two schedules is found by passing them as arguments to the also_occur() function.

The Monday of the 20th week of the year

### Assuming a week starts on Monday

in_isoweek_twenty <- in_isoweek(20)
on_mondays <- on_wday("Monday")

in_isoweek_twenty %>% 
  only_occur(on_mondays) %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-05-11"
[2] "2021-05-17"
[3] "2022-05-16"
[4] "2023-05-15"
[5] "2024-05-13"
[6] "2025-05-12"

This schedule can be created as the intersection of two schedules:

The schedule of Mondays, created using the on_wday() function.
The schedule of events occurring in ISO week 20, created using the in_isoweek() function.

The intersection of these schedules is found using the only_occur() function.

Advanced examples

Every 12th Monday, Wednesday or Friday of the year

on_mon_wed_fri <- on_wday("Mon", "Wed", "Fri")

on_nth(12,
       on_mon_wed_fri, 
       within_given = "year") %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-01-27"
[2] "2021-01-27"
[3] "2022-01-28"
[4] "2023-01-27"
[5] "2024-01-26"
[6] "2025-01-27"

This is a compound schedule with the following parts:

Days occurring on Monday, Wednesday or Friday.
The 12th occurrence of an event within a period.

We can create the first schedule using the on_wday() function.

We can then use that schedule object as an argument to the on_nth() function where we also specify that we want the 12th occurrence and that it should be within each given year.

Every 5th last Friday or Saturday of the month

on_fri_sat <- on_wday("Fri", "Sat")

on_nth(-5,
       on_fri_sat,
       within_given = "month") %>% 
  schedule_days(during = 2020)

 [1] "2020-01-17"
 [2] "2020-02-15"
 [3] "2020-03-14"
 [4] "2020-04-11"
 [5] "2020-05-16"
 [6] "2020-06-13"
 [7] "2020-07-17"
 [8] "2020-08-15"
 [9] "2020-09-12"
[10] "2020-10-17"
[11] "2020-11-14"
[12] "2020-12-12"

Just like the previous example, this can be accomplished as a compound schedule:

The first thing is to make the schedule of Fridays and Saturdays using the on_wday() function.
This schedule is then used as an argument to the on_nth() function where we also specify -5 as the first argument.

The negative integer tells the on_nth() function to look for the last occurrence of the event within the particular period rather than the first.

The first Saturday following the first Sunday of the month

on_first(on_wday("Sun"), within_given = "month") %>% 
  roll_forward(to_schedule = on_wday("Sat")) %>% 
  schedule_days(during = 2020)

 [1] "2020-01-11"
 [2] "2020-02-08"
 [3] "2020-03-07"
 [4] "2020-04-11"
 [5] "2020-05-09"
 [6] "2020-06-13"
 [7] "2020-07-11"
 [8] "2020-08-08"
 [9] "2020-09-12"
[10] "2020-10-10"
[11] "2020-11-07"
[12] "2020-12-12"

There are two components to the schedule:

The first Sunday of the month, found using the on_wday() and on_first() functions.
The Saturday following the above schedule, found by rolling it forward using the roll_forward() function.

Holidays

U.S. Independence Day

on_fourth_day_month <- on_mday(4)
in_july <- in_month("July")

on_us_independence_day <- 
  only_occur(on_fourth_day_month, 
             in_july)

on_us_independence_day %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-07-04"
[2] "2021-07-04"
[3] "2022-07-04"
[4] "2023-07-04"
[5] "2024-07-04"
[6] "2025-07-04"

In the United States Independence Day is celebrated on July 4th, regardless of the year.

This can be created as the intersection of two schedules:

The schedule of days occurring in July, found using the in_month() function.
The schedule of all days occurring on the 4th of the month, found using the on_mday().

The intersection of these schedules is found using the only_occur() function.

Martin Luther King Jr. Day

on_mondays <- on_wday("Mon")
in_jan <- in_month("Jan")

on_mlk_day <- 
  on_third(on_mondays, 
           within_given = "month") %>% 
  only_occur(in_jan) 

on_mlk_day %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-01-20"
[2] "2021-01-18"
[3] "2022-01-17"
[4] "2023-01-16"
[5] "2024-01-15"
[6] "2025-01-20"

Martin Luther King Jr. Day is a national holiday United States occurring every year on the third Monday in January.

There are three parts to this schedule:

Events occurring on Mondays, created using on_wday().
Events occurring in January, created using in_month()
The schedule of the nth event occurring in the period, in this case on_third().

The schedule of Mondays is passed into the on_third() function as an argument along with the argument specifying it should be within a given month.

You can then get the desired schedule by finding the intersection of the above schedule with the schedule of January days using only_occur().

Combine holidays

on_us_federal_holidays <-
  on_us_independence_day %>% 
  also_occur(on_mlk_day)

on_us_federal_holidays %>% 
  schedule_days(from = 2020, to = 2022)

[1] "2020-01-20"
[2] "2020-07-04"
[3] "2021-01-18"
[4] "2021-07-04"
[5] "2022-01-17"
[6] "2022-07-04"

If you want to create a schedule of multiple holidays, you can compose it using individual schedule objects of those holidays.

In this example, we take the schedule objects we have already created for US Independence Day and Martin Luther King Jr. Day and combine them using the also_occur() function.

This can be done any number of times to create a schedule that is arbitrarily complex.